feat(web): ES-module page lifecycle and one schema field model (stage 1) - #703

Stage 1 of moving the web UI to native ES modules with one schema-driven form model (roadmap theme T7, ranked opportunity 12). This is the namespace refactor that comes before any split of plugins_manager.js. It is small on purpose: it adds the pattern and proves it on one page and on the form model, and it changes no other page.

What's in it

1. Module skeleton (web_interface/static/v3/js/core/)

There is no bundler, and nothing is built on the Pi; it serves the files as they are.

Serving changes in app.py:

• .js and .mjs are pinned to text/javascript, because module scripts require a JavaScript MIME type.
• A static .js request without ?v= now gets Cache-Control: no-cache (a 304 when unchanged) instead of being cached as immutable for a year. Modules import each other by relative URL, and that URL never carries the version. Versioned URLs keep the long cache.

2. Reference page: Cache

• cache.html no longer has its 163-line inline script. Its root is data-page="cache".
• js/pages/cache.js runs the page and is loaded the first time the tab opens. Rows are built with textContent, and Delete uses one delegated listener.
• window.deleteCacheFile stays as a deprecated alias.

3. Form model foundation (src/plugin_system/field_model.py)

build_field_model(schema, config, plugin_id) walks a schema the way the render_field macro does. It returns one JSON tree, which covers:

• each field's path, label, help, widget, value, default, constraints, options and secret flag;
• the exact form controls the macro posts (inputs);
• the JS widget it mounts (mount).

It handles every branch of the macro: checkbox, toggle-switch, select, number, slider, number-input, file-upload (array and string), checkbox-group, google-calendar-picker, day-selector, custom-feeds, array-table, color-picker, comma text, text, json-file-manager, the string JS widgets, plugin-supplied widgets, schedule-picker, time-range, style-editor (with its fallback), nested sections, legacy-boolean objects, hidden fields, the advanced tier and schemaless configs. Rendering does not change yet.

4. docs/WEB_FRONTEND_ARCHITECTURE.md

The doc covers:

• the target layout;
• the lifecycle and facade contracts;
• serving modules from the Pi;
• the migration order, smallest page first and plugins_manager.js last;
• the flag-gated switch to model rendering and JSON submit, including the save-parity test that gates it;
• which JS suites cover each step.

Parity result

test/test_field_model_parity.py renders the real macro and parses the <form>. It records every named control as (name, type, submitted value, checked, options) in document order, and every widget script as (widget, name, JSON value). It then checks both lists against the model, and checks that the set of posted names is identical.

Each schema is rendered twice: once with nothing stored, and once with the config the route really renders (defaults merged, secrets masked).

Schemas covered locally: 49 files plus 2 synthetic.

• All 46 in the ledmatrix-plugins monorepo (read-only).
• plugin-repos/starlark-apps and plugin-repos/web-ui-info.
• test/fixtures/plugins/ci-fixture-plugin.
• A synthetic schema that reaches every macro branch, and a schemaless config.

That is 102 cases, 8,915 form controls and 291 widget mounts compared. No mismatches.

In CI the monorepo isn't checked out, so the synthetic schema keeps every branch covered (test_every_macro_branch_is_reached). Locally, set LEDMATRIX_MONOREPO_PLUGINS, or keep a sibling ../ledmatrix-plugins checkout.

I mutation-checked the test. Each of these model bugs makes it fail:

• dropping the checkbox-group sentinel;
• dropping the table time default;
• choosing the first <select> match instead of the last;
• dropping the number None quirk;
• missing all-hidden objects.

The model reproduces these existing macro quirks on purpose. They are for the renderer to fix later:

• 83 number fields with a null default render value="None".
• blackjack's x-widget: "color" and stock-news' tag-input fall back to a comma-separated text box.
• of-the-day's ["null", ...]-typed file_manager is drawn as a text box.
• 11 objects that have no properties render nothing.

Tests

• JS (node test/js/run_all.js with REQUIRE_DOM=1 against a local emulator server): all 19 suites pass. New suites:
  • unit/test_page_registry.js (31 checks): the lifecycle.
  • unit/test_core_modules.js (30): api and facade.
  • dom/test_cache_page.js (31): real partial and real API shape. After five swaps, one Refresh makes exactly one request; a cancelled in-flight request draws nothing; hostile keys stay text; delete, empty, error, network and login states.
  • test_html_escaping.js drops the cache.html escaper, which no longer exists.
• Python:
  • test/web_interface/test_es_modules.py covers MIME type, no-cache vs immutable, boot.js loading last, import resolution, the registered page ↔ module ↔ partial mapping, and that converted partials have no <script>.
  • The parity test.
  • scripts/build_css.py --check passes (no new utility classes).
  • field_model.py is added to the mypy ratchet, which is clean (79 modules).
• Full suite vs a baseline worktree of origin/main: the same 68 FAILED/ERROR test IDs on both (62 failed + 6 errors, all pre-existing on this Windows host); nothing new fails, nothing is fixed. Branch: 6,858 passed vs 6,826 on main (+32 new tests).
• Browser smoke (dev app in emulator mode, browser pane):
  • Cache, Logs, Operation History, General and Overview were visited ten times in turn.
  • The cache, general and logs panels were each re-swapped five more times through htmx.ajax.
  • Result: one mounted cache page, one /api/v3/cache/list request per swap and exactly one per Refresh click, and no errors from the app's own code. The same run against an origin/main server gave identical request counts.
  • Two kinds of console noise showed up, and the same run on origin/main showed both:
    • The pane was hidden, which freezes requestAnimationFrame, so Alpine logs cancelled x-transition promise rejections.
    • /api/v3/logs returns 503 because Windows has no journalctl.

Not in this PR

• No other page is converted.
• Plugin config forms still render from the macro.
• The model endpoint, the renderer and the JSON-submit flag are stages that follow, described in the doc.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added the foundation for loading Web UI pages as native modules, including shared API access and page lifecycle management.
  • Added a structured model for plugin configuration forms, covering field types, defaults, and options.
• Bug Fixes
  • Improved Cache page handling for loading, errors, deletion, and stale requests. Cache values are rendered as text.
• Documentation
  • Added guidance on the Web UI architecture and running its JavaScript tests.